home *** CD-ROM | disk | FTP | other *** search
/ Mac Format 1996 April / MacFormat CD Edition MF36 (April 1996).iso / Shareware City / Developers / Tools Plus - GUI⁄Event libs / Tools Plus 2.6.1a Evaluat'n Kit / Tools Plus 2.6.1a / User Manual / 16-User Notification < prev    next >
INI File  |  1994-09-17  |  7KB  |  116 lines
  1. [Display using Monaco 9]
  2.  
  3.  
  4. 16 User Notification
  5. ````````````````````
  6.  
  7.   This chapter describes Tools Plus’s implementation of the Macintosh toolbox’s Notification Manager.  The Notification Manager is used to tell the user that there is something happening they need, or want to be aware of in an inactive application.  This feature is available in System 6.0 (when running MultiFinder) and System 7.  An example of the Notification Manager at work is when Print Monitor tells your application it needs a sheet of paper to be inserted for a manual page feed.
  8.  
  9.   Tools Plus does more than just simplify access to the Notification Manager.  User notification is automatic whenever your application displays a Dynamic Alert box.  If your application is inactive when it uses the AlertBox routine, Tools Plus notifies the user by displaying a notification dialog such as the one shown below.
  10.  
  11.   Your application can customize how the user is notified by using the SetNotification routine.  The user can be notified by any of the following means (including and combination).
  12.  
  13.   • Display a flashing icon in the Application menu (System 7) or Apple
  14.     menu (System 6)
  15.  
  16.   • Play a sound (or the system’s default error sound)
  17.  
  18.   • Display an alert with a message in it that requires the user to
  19.     click the OK button before continuing.
  20.  
  21.   To comply with Macintosh user interface guidelines, you should think of notifications as three levels:
  22.  
  23.   1 Display a flashing icon
  24.  
  25.   2 Display a flashing icon and play a sound
  26.  
  27.   3 Display a flashing icon, optionally play a sound, and display a
  28.     message
  29.  
  30.   Ideally, your application should let the user decide if and how they want to be notified, as demonstrated by the Print Monitor’s notification options.
  31.  
  32.  
  33.  
  34.  
  35.  
  36. Notifying the User
  37. ``````````````````
  38.   Tools Plus automatically accesses the Macintosh toolbox’s Notification Manager if your application is inactive and it uses the AlertBox routine.  A default notification message is displayed.
  39.  
  40.   Your application can use the SetNotification routine to specify a small icon (‘SICN’ resource) that will flash in the menu bar during notification.  SetNotification also specifies the sound that is used (if any), and the message that is displayed in a notification alert (if any) when the user is notified.
  41.  
  42.   If your application wants to notify the user without using a Dynamic Alert, it can do so with the PostNotification routine.  If your application is inactive, PostNotification notifies the user as per the settings specified by SetNotification.
  43.  
  44.   When your application is activated, the notification is cleared.
  45.  
  46. ------------------------------------------------------------------------
  47.  
  48. SetNotification
  49. ```````````````
  50. Define the settings for notifying the user.
  51.  
  52.    pascal void SetNotification (short IconID, short SoundID,
  53.                  Str255 Message, Boolean ResetAfterUse);
  54.  
  55.    procedure SetNotification (IconID, SoundID: INTEGER;
  56.                  Message: STRING; ResetAfterUse: BOOLEAN);
  57.  
  58.   IconID is the resource ID for an ‘SICN’ small icon that is flashed in the menu bar during notification.  Tools Plus loads this resource into memory and locks it while posting the notification.  If you don’t want to display an icon, use the NoIcon constant.
  59.  
  60.   SoundID is the resource ID for an ‘snd ’ sound that is played when the user if first notified.  Tools Plus loads this resource into memory and locks it while posting the notification.  You can use the nmSysBeep constant if you want to play the default system error sound, or nmSilentNote if you don’t want to play a sound at notification.
  61.  
  62.   Message is the string that is displayed in the notification alert.  You can use the nmDefaultMsg constant if you want to use the default notification message, or the nmNoMsg constant if you don’t want a notification alert displayed.  The message can contain two string variables that are replaced by Tools Plus:
  63.  
  64.     “^0”  is replaced by the application’s name
  65.     “^1”  is replaced by the (apple) symbol in System 6, and the word
  66.               “Application” under System 7
  67.  
  68.   These two variables can be combined to produce tailored messages that adapt automatically to System 6 and System 7.  Tools Plus’s default messages is:
  69.  
  70.     “^0” needs your attention.
  71.     Please choose “^0” from the ^1 menu or click the “^0” window.
  72.  
  73.   In all cases, “^0” is replaced with your application’s name.  The “^1” is replaced by text that is dependent on the system version on which your application is running.  Therefore, the default string is automatically changed to:
  74.  
  75.   System 6:  “AppName” needs your attention.
  76.              Please choose “AppName” from the (apple) menu or click the
  77.                 “AppName” window.
  78.  
  79.   System 7:  “AppName” needs your attention.
  80.              Please choose “AppName” from the Application menu or click
  81.                 the “AppName” window.
  82.  
  83.   ResetAfterUse specifies if the notification settings should be reset to their default values after notification is posted.  If ResetAfterUse is true, the settings revert to their default values.  If ResetAfterUse is false, the specified settings remain in effect until they are changed by SetNotification.  You can use the nmResetWhenDone and nmKeepSettings constants for this item.
  84.  
  85. Also see:  PostNotification.
  86.  
  87.  
  88.   CONST                     {Notification constants…                   }
  89.     nmSysBeep       = -1;   {NOTIFICATION: Use System Error sound      }
  90.     nmSilentNote    = 0;    {              Silent notification         }
  91.     nmDefaultMsg    = ' ';  {              Use default message         }
  92.     nmNoMsg         = '';   {              Don’t display an alert      }
  93.     nmResetWhenDone = true; {              Reset to defaults after used}
  94.     nmKeepSettings  = false;{              Keep settings after used    }
  95.     NoIcon          =-32768;{ICONS: No icon used                       }
  96.  
  97. Note: If your application is displaying an icon during notification,
  98.       and/or plays a sound other than the default system error sound,
  99.       the ‘SICN’ and ‘snd ’ resources are locked in memory by Tools
  100.       Plus until your application is activated.  Therefore, you can flag
  101.       these resources as “purgeable” to save memory.
  102.  
  103. ------------------------------------------------------------------------
  104.  
  105. PostNotification
  106. ````````````````
  107. Notify the user that your application needs attention.
  108.  
  109.    pascal Boolean PostNotification(void);
  110.  
  111.    function PostNotification: BOOLEAN;
  112.  
  113.   If your application is inactive, PostNotification notifies the user that your application needs attention.  If SetNotification has been used to specify notification settings, then those settings are used.  Otherwise, Tools Plus’s default settings are used.
  114.  
  115.   If your application is inactive when PostNotification is called, the function returns true.  If your application is active, or it is running under System 5, or it is running under System 6’s Finder (not MultiFinder), PostNotification does nothing and return’s false.
  116.